﻿# Documentation API — Mecreco Wallet

## 2. Authentification

### Mécanisme

1. `POST /login` retourne un `session_token`.
2. Chaque requête authentifiée envoie le token dans le header :

```http
X-Session-Token: <session_token>
Content-Type: application/json; charset=UTF-8
```

### Convention de réponse

```json
{
  "status": "success | warning | error",
  "message": "Message lisible",
  "data": { },
  "errors": { "champ": ["erreur de validation"] }
}
```

- Succès : `statusCode == 200` (ou `201` pour `/credit-requests`) **et** `status == "success"`.
- Erreurs de validation Laravel : champ `errors` (map champ → liste de messages).

---

## 3. Endpoints

### 3.1 Authentification & mot de passe

#### `POST /login`

Connexion de l'utilisateur. Non authentifié.

**Body :**
```json
{
  "username": "string|required",
  "password": "string|required",
}
```

**Réponses :**

`200 OK` — succès :
```json
{
  "status": "success",
  "session_token": "string",
  "user": {
    "user_id": 0,
    "Client_ID": "string",
    "user_phone_number": "string",
    "name": "string",
    "account_name": "string"
  }
}
```

`200 OK` — changement de mot de passe initial requis :
```json
{ "status": "warning", "action_required": "reset_initial_password", "message": "...", "user": { "user_id": 0, "name": "..." } }
```

#### `POST /reset-password`

**Body :**
```json
{
  "identifier": "string", //peut etre username ou client_id
  "new_password": "string",
}
```

---

### 3.2 Santé / Connectivité

#### `GET /connexion-state`

**Succès :** `statusCode == 200`.

---

### 3.3 Tableau de bord

#### `GET /dashboard/{client_account_number}/all-data`

Données agrégées de l'écran d'accueil.

**Réponse `200` :**
```json
{
  "status": "success",
  "user_info": { "account_name": "string" },
  "client_account_number": "string",
  "account_balances":   [ { "currency": "string", "amount": 0.0 } ],
  "credit_balances":    [ { "currency": "string", "outstanding_amount": "0", "next_payment_amount": "0", "next_payment_date": "YYYY-MM-DD|null" } ],
  "social_shares":      [ { "id_part": "...", "description": "...", "currency": "...", "quantity": 0, "value": 0.0 } ],
  "recent_transactions":[ { voir modèle Transaction } ]
}
```

`404` → « Client non trouvé ou données indisponibles ».

---

### 3.4 Comptes épargne

#### `GET /client/{client_account_number}/savings-accounts`

**Réponse `200` :** `data` = liste de `SavingAccount` :
```json
{
  "compte_id": "string",
  "designation": "string",
  "currency": "string",
  "solde_du_compte": 0.0,
  "etat_compte": "string",
  "montant_bloque": 0.0,
  "designation_du_type_compte": "string"
}
```

---

#### `GET /accounts/saving/{account_id}/statement`

Relevé de compte sur une période.

**Query params :** `start_date=YYYY-MM-DD`, `end_date=YYYY-MM-DD`

**Réponse `200` :** `data` = liste de `StatementEntry` :
```json
{
  "transaction_date": "YYYY-MM-DD ...",
  "description": "string",
  "party": "string (déposant / bénéficiaire)",
  "debit_amount": "0|null",
  "credit_amount": "0|null",
  "running_balance": "0"
}
```

---

### 3.5 Transactions

#### `GET /transactions/{client_account_number}/get-all`

Historique paginé des transactions.

**Query params :** `page=<int>`, `per_page=<int>`, `type=<string>` (optionnel, filtre)

**Réponse `200` :**
```json
{
  "status": "success",
  "data": [
    {
      "date": "ISO8601",
      "description": "string",
      "amount": "0|string",
      "currency": "string",
      "is_credit": "0|1",
      "destination_account": "string|null",
      "reference": "string|null",
      "status": "string|null",
      "transaction_type": "string",
      "observationTransact": "string"
    }
  ],
  "pagination": { "last_page": 0 }
}
```

---

### 3.6 Virements & bénéficiaires

#### `GET /account/search`

Recherche d'un compte bénéficiaire.

**Query params :** `query=<texte>`, `currency=<devise source>`, `source_account=<compte source>`

**Réponse `200` :** `data` = liste de :
```json
{ "account_id": "string", "designation": "string", "currency": "string", "client_id": "string" }
```

---

#### `GET /account/validate/{account_id}`

Valide l'existence d'un compte.

**Réponse `200` :** `data` = `{ "designation": "string", "currency": "string" }`

---

#### `POST /transfer`

Exécute un virement

**Body :**
```json
{
  "username": "string",
  "source_account_id": "string",
  "destination_account_id": "string",
  "amount": 0.0,
  "description": "string|null"
}
```

**Réponse `200` :**
```json
{
  "status": "success",
  "message": "...",
  "data": {
    "source_account_new_balance": 0.0,
    "transaction_reference": "string",
    "transaction_date": "string"
  }
}
```

---

### 3.7 Crédits

#### `GET /credit/{client_account_number}/all-credit`

**Réponse `200` :** `data` = liste de `CreditAccount` :
```json
{
  "account_id": "string",
  "designation": "string",
  "currency": "string",
  "credit_limit": "0",
  "outstanding_balance": "0",
  "available_credit": "0",
  "interest_rate": "string",
  "due_date": "string|null",
  "minimum_payment_due": 0.0,
  "status": "string",
  "source_saving_account_id": "string",
  "source_saving_account_name": "string|null",
  "loan_disbursement_date": "string",
  "loan_maturity_date": "string",
  "number_of_deferred_days": "0",
  "frequenceVersement": "string"
}
```

---

#### `GET /credit/{account_id}/schedule`

Calendrier de remboursement d'un crédit.

**Réponse `200` :** `data` = liste de `RepaymentInstallment` :
```json
{
  "payment_date": "string",
  "payment_amt": "0",
  "loan_bal": "0",
  "inst_no": "0",
  "principal_due": "0",
  "interest_due": "0",
  "principal_paid": "0",
  "interest_paid": "0",
  "penalty_paid": "0",
  "amount_paid": "0",
  "tran_reference": "string"
}
```

---

#### `POST /credit-requests`

Soumission d'une demande de crédit.

**Body :**
```json
{
  "user_id": "string",
  "username": "string",
  "guarantee": "string",
  "amount": 0.0,
  "currency": "string",
  "duration": 0,
  "reason": "string",
  "user_phone_number": "string"
}
```

**Succès :** `201 Created` — `{ "message": "..." }`

---

### 3.8 Parts sociales & dépôts à terme

#### `GET /social-shares/{client_account_number}/all-social-shares`

**Réponse `200` :** `data` = liste de `SocialShare` :
```json
{ "id_part": "...", "description": "string", "currency": "string", "quantity": 0, "value": 0.0 }
```

---

#### `GET /fixed-deposits/{client_account_number}/all-fixed-deposits`

**Réponse `200` :** `data` = liste de `FixedDeposit` :
```json
{
  "id_dat": "...",
  "description": "string",
  "currency": "string",
  "duration": "0",
  "date_debut": "YYYY-MM-DD",
  "date_fin": "YYYY-MM-DD",
  "montant": "0",
  "taux_interet": "0",
  "total_interet": "0",
  "etat": "string"
}
```

---

### 3.9 Transaction de dépot et retrait

#### `POST /mobile-transaction`

Initie un dépôt ou retrait. Le `transaction_id` (UUID v4) est généré côté client pour l'idempotence / le suivi.

**Body :**
```json
{
  "account_id": "string",
  "telephone": "string",
  "montant": 0.0,
  "devise": "string",
  "type": "depot | retrait",
  "transaction_id": "uuid-v4"
}
```

---

#### `GET /mobile-transaction/{transaction_id}/status`

**Réponse `200` :**
```json
{
  "status": "pending | success | failed | error",
  "message": "string",
  "transaction_date": "string|null"
}
```

> Ici `status` est le **statut métier** de la transaction (pas l'enveloppe `success` des autres endpoints).

---


### 3.10 Taux du jour, support et volume de transactions

#### `GET /taux-du-jour`

Taux de change du jour (dernière date disponible dans `t_taux_du_jour`).

**Query params (optionnels) :** `date=YYYY-MM-DD`, `agence_id`

**Réponse `200` :** `data` = liste de :
```json
{ "CodeAgence": "string", "CodeDevise": "string", "CodeDeviseTo": "string", "operation": "*|/", "taux": "0", "date_du_jour": "YYYY-MM-DD" }
```

---

#### `GET /support-number`

Numéro de téléphone du support client (clé `service-client` de `t_setting_compte_principals`).

**Réponse `200` :**
```json
{ "status": "success", "data": { "support_number": "string" } }
```

---

#### `POST /support-messages`

Envoie un message au support.

**Body :**
```json
{
  "account_number": "string|required",
  "message": "string|required",
  "subject": "string|null",
  "username": "string|null",
  "telephone": "string|null"
}
```

**Succès :** `201 Created` - `{ "status": "success", "data": { "id": 0 } }`

---

#### `GET /accounts/{account_id}/transaction-volume`

Volume de transactions d'un compte (débit/crédit), groupé par jour ou par mois.

**Query params :**
- `period` = `daily` (défaut) | `monthly`
- `date` (YYYY-MM-DD) — défaut : aujourd'hui.
  - `daily` : volume de la journée indiquée.
  - `monthly` : volume du mois entier contenant la date (ex. `2026-01-15` => du `2026-01-01` au `2026-01-31`).

**Réponse `200` :**
```json
{
  "status": "success",
  "data": {
    "account_id": "string",
    "period": "daily|monthly",
    "start_date": "YYYY-MM-DD",
    "end_date": "YYYY-MM-DD",
    "volumes": [
      { "period": "YYYY-MM-DD|YYYY-MM", "currency": "string", "total_credit": "0", "total_debit": "0", "transaction_count": 0 }
    ],
    "totals": [
      { "currency": "string", "total_credit": 0, "total_debit": 0, "transaction_count": 0 }
    ]
  }
}
```

---


---

#### `POST /accounts/statement-sms`

Envoie un relevé court du compte par SMS (solde + 3 dernières opérations). Le SMS est envoyé au numéro du client, ou au `telephone` fourni.

**Body :**
```json
{
  "account_id": "string|required",
  "telephone": "string|null"
}
```

**Réponse `200` :**
```json
{ "status": "success", "data": { "telephone": "string", "sms_response": "..." } }
```

**Modèle de SMS envoyé :**
```
Relevé court - Compte N° {NUMERO_COMPTE}
Solde : {SOLDE_ACTUEL} {DEVISE}
Dernières opérations :
• {DATE} : +{MONTANT} (Dépôt)
• {DATE} : -{MONTANT} (Retrait)
```

---
## 4. Récapitulatif

